home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Night Owl 6
/
Night Owl's Shareware - PDSI-006 - Night Owl Corp (1990).iso
/
015a
/
gport101.zip
/
GPORT.DOC
< prev
next >
Wrap
Text File
|
1991-08-31
|
25KB
|
1,117 lines
Gport
C Language Game Port Library
Version 1.01
1 September 91
Copyright (c) 1991 Bri Productions
1
Table of Contents
Introduction
General Description.....................3
Disclaimer..............................3
Registration............................3
Contacting the Author...................3
A typedef...............................3
General Functions
Description.............................4
GamOpen.................................5
GamClose................................6
GamAxis.................................6
GamAxes.................................7
GamButton...............................8
Calibration Functions
Description............................10
GamRawAxis.............................11
GamCalAxis.............................12
GamCenter..............................13
Appendix A - Things to Look Out For............15
Appendix B - Joystick Calibration/Centering....16
Appendix C - Registration Form.................18
2
General Description.
Gport is a C language, high speed, high resolution game port
library for IBM and compatible computers. Gport is compatible
with most if not all DOS based C compilers.
Some of Gport's features are:
∙ Timer driven button monitor.
∙ Optional joystick calibration.
∙ Choice of REAL or MEAN centering modes.
∙ Yields higher resolution on faster computers.
∙ Constant axis scaling to approximately ±1000.
∙ Written in assembly language for optimum speed and efficiency.
DISCLAIMER.
Gport is provided AS IS. Bri Productions specifically disclaims
any and all warranties, expressed or implied, including fitness
for a particular purpose. Use this product at your own risk.
Registration.
Gport is a user supported software product. Distribution of
this product, unaltered and without charge, is encouraged. If
you find this product useful, you are encouraged to register
your copy. This allows Bri Productions to continue to provide
and support low cost, high quality shareware.
The registration fee is $15.00 US dollars and includes libraries
for small, medium, compact and large memory models and complete
source code. A registration form is provided in Appendix C.
Contacting the author.
Bri Productions may be contacted by any of the following means:
CompuServe - 76635,2246
U.S. mail - Bri Productions
P.O.Box 7121
Fremont, CA 94537-7121
CompuServe is a trademark of CompuServe Inc.
A typedef.
You will see the data type 'byte' throughout the Gport library.
This is a typedef defined in gport.h. Byte is an unsigned
character used for byte size values.
3
General functions
There are two functions that are required before other game
port functions can be called. They are GamOpen() and GamClose().
GamOpen() initializes the game port and installs an interrupt
handler for monitoring the buttons. GamClose() releases the
interrupt handler. Failing to call GamClose() prior to the
program's termination will most certainly cause an operating
system crash.
GamAxis() and GamAxes() fetches the position(s) of one or
more joystick axes. A full up or right joystick returns a value
of approximately +1000 and full down or left returns a value of
approximately -1000. GamButton() fetches the status of the game
port's buttons. Information on a button pressed since the last
call to GamButton() as well as a presently pressed is available.
4
----------------------------------------------------------------
GamOpen
----------------------------------------------------------------
Function
Initializes the game port and installs the interrupt
handler.
Syntax
#include "gport.h"
int GamOpen(void);
Remarks
GamOpen initializes the game port. If an axis is found to
be valid, it's corresponding bit is set in the returned
status word. After a call to GamOpen, a subsequent call
to GamClose is required. Failure to do so will most
definitely cause the operating system to crash.
Return Value
GamOpen returns a valid axis status word. The bits/values
are defined as follows:
JAX_VAL (0x1) - Joystick A, x axis valid
JAY_VAL (0x2) - Joystick A, y axis valid
JA_VAL (0x3) - Joystick A, both axes valid
JBX_VAL (0x4) - Joystick B, x axis valid
JBY_VAL (0x8) - Joystick B, y axis valid
JB_VAL (0xC) - Joystick B, both axes valid
See also
GamClose
Example
Attempt to open the game port and check Joystick A.
{
int valid_axes;
valid_axes = GamOpen();
if((valid_axis & JA_VAL) == JA_VAL)
{
...Joystick A OK
}
}
5
----------------------------------------------------------------
GamClose
----------------------------------------------------------------
Function
Releases the interrupt handler.
Syntax
#include "gport.h"
void GamClose(void);
Remarks
After a call to GamOpen, a subsequent call to GamClose
is required. Failure to do so will most definitely cause
the operating system to crash.
See also
GamOpen
Example
Close the game port prior to terminating.
{
...closing code
GamClose();
exit(0)
}
----------------------------------------------------------------
GamAxis
----------------------------------------------------------------
Function
Gets the coordinate of a joystick axis.
Syntax
#include "gport.h"
signed GamAxis(byte axis);
6
Parameters
axis - Constant that defines which axis to get the
coordinate of. Possibilities are:
JAX (0) - Joystick A, X axis
JAY (1) - Joystick A, Y axis
JBX (2) - Joystick B, X axis
JBY (3) - Joystick B, Y axis
Remarks
GamAxis fetches the coordinate of a single joystick
axis. The coordinate is returned as a signed integer.
Return value
GamCoord returns the coordinate of the specified axis.
The values will range from -1000 to +1000.
See also
GamAxes GamButton
Example
Update the current positions of the X & Y axes for
joystick A.
{
YourXaxisFunction( GamAxis(JAX) );
YourYaxisFunction( GamAxis(JAY) );
}
----------------------------------------------------------------
GamAxes
----------------------------------------------------------------
Function
Gets the both axes coordinates of a joystick.
Syntax
#include "gport.h"
void GamAxes(byte stick, signed *x, signed *y);
7
Parameters
stick - Constant that defines which joystick to get
the coordinates of. Possibilities are:
JA (0) - Joystick A
JB (1) - Joystick B
x - pointer to the signed integer where the x axis
coordinate will be stored.
y - pointer to the signed integer where the y axis
coordinate will be stored.
Remarks
GamAxes fetches the coordinates of both axes for
the specified joystick. The coordinates are stored
at the pointers passed to GamAxes. The values will
range from -1000 to +1000.
See also
GamAxis GamButton
Example
Update the current positions of the X & Y axes for
joystick A.
{
signed x,y;
GamAxes(JA, &x, &y);
YourXaxisFunction( x );
YourYaxisFunction( y );
}
----------------------------------------------------------------
GamButton
----------------------------------------------------------------
Function
Gets the status of the joystick buttons.
8
Syntax
#include "gport.h"
byte GamButton(void);
Remarks
GamButton returns the current status of the joystick
buttons as well as any button status since the last
call to GamButton.
Return value
GamButton returns the status of the joystick buttons.
If the button is currently pressed, it's current bit
will be set. If a button has been pressed since the
last call to GamButton, it's pending bit is set.
The bit constants are as follows:
BA1_CURR (0x01) - Joystick A, button 1 current.
BA2_CURR (0x02) - Joystick A, button 2 current.
BB1_CURR (0x04) - Joystick B, button 1 current.
BB2_CURR (0x08) - Joystick B, button 2 current.
BA1_PEND (0x10) - Joystick A, button 1 pending.
BA2_PEND (0x20) - Joystick A, button 2 pending.
BB1_PEND (0x40) - Joystick B, button 1 pending.
BB2_PEND (0x80) - Joystick B, button 2 pending.
See also
GamAxis GamAxes
Example
Check if the player has fired (button 1). If so
call the fire update function.
#define FIRE (BA1_PEND) | (BA1_CURR)
{
if(GamButton() & FIRE)
{
YourFireFunction();
...more code
}
}
9
Calibration Functions
The performance of the joystick can be significantly improved
by calibrating it, especially if the joystick is misaligned.
This is achieved by collecting the raw value of the position of
the joystick extremes; full up, down, left, and right; and
recalculating scaling math. GamRawAxis() fetches the raw
value of the position of the joystick, which is passed to the
function GamCalAxis(). GamCalAxis() then recalculates the
scaling math.
The calibration is done in two steps in order to leave open
the option of saving the raw values to disk for future
reference. This saves the step of having to recalibrate
every time a program is run.
GamCenter() sets the centering mode. There are two ways to
determine where the center of a joystick is. The REAL center
is defined as where the joystick comes to rest. The MEAN
center is defined as the mean between the joystick extremes.
For a more detailed description on calibration, see Appendix B.
10
----------------------------------------------------------------
GamRawAxis
----------------------------------------------------------------
Function
Gets the raw value of a joystick axis.
Syntax
#include "gport.h"
unsigned GamRawAxis(byte axis);
Parameters
axis - Constant that defines which axis to get the
coordinate of. Possibilities are:
JAX (0) - Joystick A, X axis
JAY (1) - Joystick A, Y axis
JBX (2) - Joystick B, X axis
JBY (3) - Joystick B, Y axis
Remarks
GamRawAxis returns the raw value of a joystick position
to be used for calibrating the joystick . Smaller values
are to the left and up while larger values are to the
right and down. The actual value will vary from machine
to machine.
Return value
GamRawAxis returns the raw value for the position of
the selected joystick axis.
See also
GamCal GamCenter
Example
Calibrate the X axis on joystick A.
{
int raw_ax_right;
int raw_ax_left;
puts("Hold joystick full right and press any key");
getch();
11
raw_ax_right = GamRawAxis(JAX);
GamCalAxis(JAX, raw_ax_left);
puts("Hold joystick full left and press any key");
getch();
raw_ax_left = GamRawAxis(JAX);
GamCalAxis(JAX, raw_ax_right);
}
----------------------------------------------------------------
GamCalAxis
----------------------------------------------------------------
Function
Calibrates a joystick axis extreme from a raw value.
Syntax
#include "gport.h"
void GamCalAxis(byte axis, unsigned raw_value);
Parameters
axis - Constant that defines which axis to get the
coordinate of. Possibilities are:
JAX (0) - Joystick A, X axis
JAY (1) - Joystick A, Y axis
JBX (2) - Joystick B, X axis
JBY (3) - Joystick B, Y axis
raw_value - Raw value returned from a call to GamRaw
on which to calibrate.
Remarks
GamCalAxis calibrates a joystick extreme from a raw
value from a previous call to GamRawAxis. Notice that
it is not necessary to specify the extreme (left/right
or up/down) in question.
See also
GamRawAxis GamCenter
12
Example
Calibrate the X axis on joystick A.
{
puts("Hold joystick full right and press any key");
getch();
GamCalAxis(JAX, GamRawAxis(JAX));
puts("Hold joystick full left and press any key");
getch();
GamCalAxis(JAX, GamRawAxis(JAX));
}
----------------------------------------------------------------
GamCenter
----------------------------------------------------------------
Function
Sets the centering mode.
Syntax
#include "gport.h"
void GamCenter(byte mode);
Parameters
mode - Constant defining the centering mode to be used.
Possibilities are:
* REAL (0) - real centering mode.
MEAN (1) - mean value centering.
* default
Remarks
GamCenter sets the centering mode to be used. In real
mode, the center of an axis will be where the joystick
is at rest. In mean mode, the center is calculated as
the mean between the two previously calibrated extremes.
For a more detailed description of the centering
modes see Appendix B.
See also
GamRawAxis GamCalAxis
13
Example
Set the centering to mean mode.
{
GamCenter(MEAN);
}
14
Appendix A
Things to look out for.
∙ Gport installs a timer interrupt at interrupt 0x1C (user
timer link). Gport does not take over this interrupt but
chains into it.
∙ Some faster machines will exhibit a "fold back" on the down
and right strokes of the joystick. Special AT game ports
are available which usually resolve this problem.
15
Appendix B
Calibration
When the function GamOpen() is called, some assumptions are made
about the raw values of the positions of the joystick extremes;
left, right, up and down. The assumptions are based on the raw
value of the joystick axes at the time of the call to GamOpen()
(at rest at the center). In most cases the joystick will perform
reasonably well providing the alignment of the joystick is at
least fair.
The performance of the joystick can be greatly improved if it
is calibrated. Even a poorly aligned joystick can be made to
appear to perform quite well. In order to accomplish this the
assumptions about the joystick extremes must be replaced by
their actual raw values. This requires the cooperation of the
user as well as the functions GamRawAxis() and GamCalAxis().
Typically the user will be prompted to hold the joystick to
each of the four extremes and hit a key on the keyboard. For
each extreme, the raw value of the joystick position is read
by a call to GamRawAxis() and the returned value is passes to
GamCalAxis(). GamCalAxis will then make some recalculations
and replace the previous assumptions (or calibration).
Notice that the calibration is done in two steps. First the
raw value is fetched and then it is passed. This allows the
program to store the raw values for future reference. Next
time the program is run, the values can be retrieved and
passes directly to GamCalAxis(). This saves the step of
having to interface with the user and calling GamRawAxis()
every time the program runs.
Centering
There are two ways to interpret where the center of the
joystick is . One way is to define the center as being where
the joystick comes to rest. Gport port refers to this as REAL
mode. The second way is to define the center as being
equidistant, or at the mean, from all of the joystick extremes.
Gport refers to this centering mode as MEAN mode.
REAL mode has the obvious advantage that the joystick will
always return approximately to the center. This will preclude
any drifting. The disadvantage of REAL mode is that there is
no evidence of how well the joystick is actually aligned.
The advantage and disadvantage of MEAN mode is the complement
of those of REAL mode. Drift will occur if the joystick is
not aligned well. But since there will be the evidence of
the joystick's misalignment, MEAN mode could be used to
actually align a joystick.
16
Recall that MEAN mode refers to the joystick extremes. Also
recall that the joystick extremes are assumed until the
joystick is calibrated. For this reason there is little
difference between the two centering modes until the joystick
is calibrated. Calculating the mean center using the assumed
extremes will result in the same center since the reverse
process is used to calculate the assumed extremes.
17
Appendix C
Gport Registration Form
Name: ______________________________________________________
Company: ___________________________________________________
Address: ___________________________________________________
City: ____________________________ State: _________________
Zip code: _________________ Phone # : _____________________
CompuServe # : _____________________________________________
How did you acquire Gport ? _________________________________
____________________________________________________________
What functions do you find most useful ?____________________
____________________________________________________________
What functions do you find least useful ?___________________
____________________________________________________________
What functions, not in Gport, would you like to see ?_______
____________________________________________________________
What other types of libraries would you find useful ?_______
__ Serial Communications __ Expanded Memory __ IEEE/GPIB
Others: ____________________________________________________
registration $ 15.00
California residents add sales tax ( 8.25% ) $________
shipping inside continental U.S. ( $ 2.00 )
shipping outside continental U.S. ( $ 5.00 ) $________
Total: $________
All Payments Must be in U.S. Dollars
Make check or money order payable to: Bri Productions
P.O. Box 7121
Fremont, CA 94537-7121
18
